A three-dimensional clock powered by QuickDraw¬ 3D
Jade╒s End Software
⌐ Copyright 1995 John David N. Dionisio
dondi@cs.ucla.edu
About Clock^3
Clock^3 (pronounced ╥clock cubed╙) is a clock program that works in the third dimension. Thanks to Apple╒s QuickDraw¬ 3D technology, the clocks that Clock^3 displays in its windows are fully interactive three-dimensional objects that you can rotate, zoom into or out of, and otherwise manipulate in full 3D space. Standard 3DMF files can also be imported into Clock^3 and given a set of simple clock hands. Those with more advanced 3D modeling software can create full-blown clocks in 3DMF; details are provided below.
Clock^3 is the first installment in a planned suite of three-dimensional applications collectively called Cubicle. When completed, Cubicle will be a set of desk accessories that are fully, three-dimensionally interactive. Watch out for additional QuickDraw¬ 3D-savvy Cubicle programs from this developer.
Because Clock^3 uses Apple╒s QuickDraw¬ 3D technology, it requires a Power Macintosh with at least 16M of RAM. Needless to say, QuickDraw¬ 3D must also be installed in your system.
System Requirements
Clock^3 requires a Power Macintosh with QuickDraw¬ 3D version 1.0.3 or higher and at least 16 megabytes of total memory. It has been explicitly tested on the following systems: Power Macintosh 8500/120 with 32 megabytes of memory and System 7.5.2, Performa 5200/75 with 16 megabytes of memory and System 7.5.1, and Power Macintosh 7200/90 with 16 megabytes of memory and System 7.5.2.
User Guide
Clock^3 (pronounced ╥clock cubed╙) opens windows that display either its default internal 3D clock or a clock based on a 3DMF file on disk. The following paragraphs summarize the various controls, commands, and options in Clock^3. Clock^3 also has extensive balloon help, so you can get most of the information below (except for the keyboard shortcuts) by choosing ╥Show Balloons╙ from the Help menu.
Window Controls
A clock window in Clock^3 has the following controls and functions:
Close box: Dismisses the clock window. If the clock within the window has been changed and needs to be saved, Clock^3 will ask you if you want to do so.
Zoom box: Toggles between the standard clock size (full screen) and the user-defined size, as set by the Resize box.
Resize box: Though invisible in Clock^3, the resize box is located in the usual place on the lower-right corner of the window.
3D manipulation: Click and drag within the window area to rotate the clock; certain modifier keys (see below) can change this so that instead of rotating, you are either moving or zooming in/out.
Keyboard Shortcuts
The following keyboard shortcuts can be used within a clock window. To use them, hold down the specified keys while dragging the mouse within the clock window.
zoom in/out instead of rotate control key
move instead of rotate shift key
drag-and-drop the clock from one window to another command (≡) key
Menu Commands
The following functions are available via menu commands:
File Menu
New: Opens a new clock window. The clock that is opened is either Clock^3╒s internal default clock or a 3DMF file specified by the user (see Clock^3 Preferences below).
Open╔: Opens a new clock window on a standard 3DMF file on your hard disk. This includes files that were modified then saved using Clock^3.
Close: Closes the frontmost clock window.
Page Setup╔, Print╔: Disabled, because Clock^3 does not have any printing features. Use the Copy command or Macintosh drag-and-drop to place a copy of the clock in the window in an application that is capable of printing out PICT or 3DMF information.
Save: Saves the current clock to its associated file. If the clock has never been saved, Clock^3 will prompt you for a file name.
Save As╔: Saves the current clock under a file name that you provide. If a file with that name already exists, you will be asked if you want to replace it.
Revert to Saved: Eliminates any changes you have made to the current clock be re-reading the last saved version of the clock╒s file.
Quit: Quits from Clock^3.
Edit Menu
Undo: Disabled, because this operation is not present in Clock^3.
Cut: Moves the current content of the frontmost clock window onto the clipboard, thus leaving that window empty.
Copy: Copies the current content of the frontmost clock window onto the clipboard. The content of the clock window itself is unchanged.
Paste: Copies the current content of the clipboard onto the frontmost clock window. In order to perform a paste operation, the clipboard must contain 3DMF data (i.e. another QuickDraw 3D model that was copied onto the clipboard).
Select All: Disabled, because this operation is not present in Clock^3.
Preferences╔: Displays the Clock^3 Preferences dialog box. See below for an explanation of the Clock^3 Preferences dialog box.
Clock Menu
Add Hands╔: If the clock on the frontmost window does not have a valid set of clock hands yet, this command opens a dialog box that permits you to add a set of hands to that clock. See below for an explanation of the Add Hands dialog box.
Remove Hands: If the clock on the frontmost window currently has a set of clock hands, this command removes those hands from that clock.
Restore Camera: This command sets the 3D camera of the frontmost window to the window╒s original 3D camera position and orientation..
Set Ambient Light╔: This command sets the brightness and color of the ambient light in the scene.
Set Background Color╔: This command sets the background color of the scene.
Tick Sound: Toggles the presence of an audible tick-tock sound for the clock.
The Clock^3 Preferences Dialog Box
This section explains the options available in the Clock^3 Preferences dialog box.
Default Clock
Use this section to determine the clock that gets displayed when Clock^3 starts up or when New is chosen from the File menu. Note that because the default clock determines how new clocks are created, and not how already-open clocks look, options chosen in this section are not evident until you either quit and re-open Clock^3 or issue the New command in the File menu to create a new 3D clock.
Use Factory Clock / Use 3DMF Clock File: Use these radio buttons to determine the clock model to be used by Clock^3. The factory clock is a built-in clock that Clock^3 can create at any time. The 3DMF clock is based on a 3DMF file that exists somewhere on your system.
Choose Face Color╔: This button opens a color selection dialog box that determines the color of the factory clock╒s face and body.
Choose Jewel Color╔: The factory clock has a small ╥jewel╙ on its face that indicates the 12 o╒clock position. Click this button to set its color.
Choose Clock File╔: Click this button to choose a 3DMF file on your system from which Clock^3 will build its 3D clock. This file can be any standard 3DMF file. Be aware of the file╒s size and complexity; these factors greatly affect the speed with which Clock^3 starts up.
Add Hands Automatically: Check this box if you want Clock^3 to add hands automatically to the 3D model that does not have any such hands. A 3DMF file has clock hands if they meet the criteria described in the section Technical Details. If you do not check this box and the chosen 3DMF file does not have any clock hands, you will get a static 3D model that will not function as a clock until you manually add hands to it.
Use File╒s Clock Setup: Some 3DMF files describe not only the geometry or shape of a clock, but also the colors, camera angles, or other information that relates to the scene within which the 3D model exists, and not to the model itself. In addition, when you save a file in Clock^3, additional information such as window position, colors and setups of clock hands, audibility of clock ticks, etc., are also saved. When Use File╒s Clock Setup is checked, Clock^3 will use the information in the 3DMF file to build the overall 3D scene (if the information is present). When Use File╒s Clock Setup is not checked, only the shape or geometry of the model is read from the 3DMF file is taken into account. The view or scene settings used will be those found in the Default Clock Environment section of the preferences.
Clock Hands
This section relates to the manual addition of clock hands to 3DMF files that do not already have them. It has one control, the Default Hand Setup╔ button. This button, when clicked, invokes the Add Hands dialog box (see below).
Using the Add Hands dialog box, you can pre-configure a default set of hands to be used by Clock^3. This default hand setup will be used to add a set of clock hands to a 3D model in the following circumstances:
Ñ you have opened a 3DMF file created by another program, that file does not have any clock hands that Clock^3 recognizes, and you select Add Hands╔ from the menu bar
Ñ you have specified a 3DMF file as the default new clock, that file does not have any clock hands that Clock^3 recognizes, and you have chosen the Add Hands Automatically option
In other words, the default hand setup that you specify in the Clock Hands section is used whenever a new set of hands is requested and no other hand setup is available. For example, the default hand setup will not be used in the following situations:
Ñ you have added a new set of customized clock hands to a model, then removed them, then selected Add Hands╔ from the menu bar sometime later ╤ in this case, instead of the default hand setup, the previous hand setup defined for that model is used
Ñ you have added a new set of customized clock hands to a model, then removed them, then saved the 3DMF file to disk ╤ when you later open that file and try to add clock hands to it, the previous hand setup that you defined before saving the file is used
The general rule of thumb for hand setup is this: if you have never before defined a set of clock hands for a file, the default hand setup in the Clock Hands section is used. However, if a set of clock hands has been defined for a file at least once but later removed, when the Add Hands╔ command is later invoked on that file, that previous set of clock hands is used instead of the default hand setup.
Default Clock Environment
Use the settings in this section to determine parameters that affect the overall scene of the 3D clock. These parameters are used for the factory clock or for a 3DMF clock file whose Use File╒s Clock Setup option is not selected.
Ambient Light╔: Click this button to determine the brightness and color of the ambient light for the overall scene.
Background Color╔: Click this button to choose the color of the background area of the scene.
Tick Sound: Click this button if you want new clocks, by default, to run with an audible tick.
Factory Settings
Click on the Factory Settings button to restore all of the preferences to a ╥clean╙ version ╤ that is, the set of preferences which Clock^3 uses when it is started up for the first time.
The Add Hands Dialog Box
Use the Add Hands dialog box to define a clock hand setup. As discussed previously, a clock hand setup needs to be defined in two places: first as a default hand setup in the Preferences dialog box, and second when manually adding clock hands to a model that does not already have them. Ideally, I would have wanted a fully visual, highly interactive interface for defining clock hands; however, I do not have the time nor resources to achieve that goal. In fact, if I did that, I may as well write a full-blown 3D modeling program! So, please bear with the somewhat arduous way that the Add Hands dialog box is set up.
The Add Hands dialog box consists of a 3D wireframe preview of how the clock hands are to appear. You are provided with a limited set of controls for adjusting the 3D preview: rotating along one axis, moving the camera backward and forward, etc. Use Balloon Help for specific instructions on each of the 3D preview controls.
Clock hands have four major elements: a position, a direction, size, and color. I will discuss each of them here; their corresponding controls in the Add Hands dialog box should be pretty evident. Use Balloon Help for specific instructions on each control.
Position
Position determines where the clock hands are located. The position is specified as a three-dimensional point; specifically, this point is the fulcrum around which the clock hand rotates. Just experiment with these coordinate values to get a feel for how they affect a clock hand╒s location.
Direction
Direction is a little more complicated; it determines how the clock hands rotate when they tell time. Direction here is expressed as a 3D vector; for those of a non-mathematical bent, think of a vector as an arrow in 3D space.
The arrow relates to the clock hand in the following manner: real life clock hands turn around some kind of axle or rod, right? Well, the direction vector is precisely that axle: the clock hand rotates as if one end of the hand were fastened to it. The math-aware will recognize this vector as being normal to the clock hand.
For example, the default direction vector is (0, 0, 1). This means that the arrow lies on the z axis, and, in a default state, that z axis points toward you in the positive direction. Thus, the clock hands rotate as you would expect them to rotate when you are looking at the clock face head on: clockwise, and perpendicular to your line of sight. To make a clock hand rotate counterclockwise when facing you, set the direction vector to (0, 0, ╨1). Similarly, you can make the clock hand rotate in virtually any which way by tweaking the direction vector as appropriate.
Size
Thankfully, it╒s downhill from here. Size consists of the length and width of a clock hand. Note that for simplicity, I fix the thickness of a clock hand; thus, the wider a clock hand is, the flatter it looks.
Color
Color is another thankfully simple attribute of a clock hand. Click on the appropriate Color╔ button to assign it; you can give a different color to the hour, minute, and second hand.
Two other buttons help you to quickly set up the clock hands: Factory Settings and Preferred Settings. The Factory Settings button automatically fills the dialog box with the standard, factory-preset position, direction, size, and color of the clock hands. The Preferred Settings button does the same, except that the setup it fills in corresponds to whatever the default hand setup is, as set from the Preferences dialog box.
Technical Details
The user interface for creating, editing, and configuring clock hands is limited by design. This is primarily because shooting for the moon with clock hand definition would have meant pretty much writing a ╥real╙ 3D-modeling program, which is currently beyond my reach. Thus, you can view the clock hand setup features of Clock^3 as sort of a toy, to play with and experiment with, just to see what you can make it do. After all, Clock^3╒s real purpose is to display a 3D clock, and not to build one!
In this section, I provide instructions for the more 3D-savvy on how to create truly custom clocks. Ideas include a Mickey Mouse watch, sundial-like clocks, etc. I will use QuickDraw¬ 3D╒s terminology here; please translate as necessary into the terminology of your favorite 3D modeler.
Clock^3 recognizes a set of clock hands if the following conditions are met:
Ñ the clock hands are QuickDraw¬ 3D group objects
Ñ these group objects are the last three objects in the overall group of the model
Ñ these group objects contain a RotateAboutAxis transformation object
If these objects are found in a model, then Clock^3 tries to rotate them based on the current time. The kind of rotation involved is embedded in the RotateAboutAxis transformation (this corresponds directly to the direction vector described above).
Therefore, to create a truly custom clock, create a 3D model whose last three objects satisfy the above criteria. One final note: as I do not have access to a QuickDraw¬ 3D-savvy modeler, the above technical details have not been fully tested. I can only say that I wrote Clock^3 to follow the above rules; whether it really does follow them in all cases remains to be seen. I will appreciate any feedback, effusive or constructive, from anyone who takes an interest in this program!
Known Problems and Cautions
Because this developer does not have very much in term of time or material resources, and also because QuickDraw¬ 3D is still a nascent and very challenging technology, I╒d like to mention a few caveats to users of Clock^3:
Ñ For some reason, Clock^3 works with QuickDraw¬ 3D 1.0.3 but not with QuickDraw¬ 3D 1.0. I note this as a problem because I see no reason for why this is happening, and my many years of programming makes me hesitate from blaming QuickDraw¬ 3D 1.0 right off the bat, unless I see official documentation from the QuickDraw¬ 3D folks.
Ñ Be careful with large 3DMF models, or keeping many 3DMF models open at once; make sure that your system configuration (i.e. amount of available RAM) can handle the models that you use. As a very small developer with limited resources, I have not been able to track down all memory-related errors. At the very least, I can say with confidence that most of these errors occur in high memory demand situations, i.e. large 3DMF models or sufficiently many open 3DMF models. So please be careful when your Clock^3 usage falls into either category.
Ñ Performing a drag-and-drop operation between two Clock^3 windows may hang or crash your machine. Drag-and-drop between Clock^3 and the Finder is also sometimes unpredictable, although it does not cause a crash. Instead, the resulting Finder clipping file is sometimes a blank picture. However, drag-and-drop between Clock^3 and the Scrapbook (or other applications that use the standard QuickDraw¬ 3D Viewer) seems to work fine based on my testing.
Ñ There is a small annoyance in the Add Hands dialog box that I have been unable to fix: when you click on any of the Color buttons (for setting the colors of the clock hands) then dismiss the resulting color selection dialog box, the underlying 3D preview gets displaced upon being redrawn for the first time (as a result of dismissing the color selection dialog box). This problem seems to be quite harmless ╤ a quick rotate or other action that update the 3D preview fixes the situation.
Credits
Many thanks to my beta testers: Herman Atienza and the Lombos brothers.
In what may become a common thread in most of my software, many thanks go to Chris Larson for much technical and religious guidance. Now if only Santa had stuffed your stocking with a couple of 8-meg SIMMs this Christmas╔
Legal & Contact Information
Clock^3 is volunteerware ╤ that is, you are free to provide any kind of positive reinforcement to the programmer (grin) if you like his software. But seriously, at the very least, I would very much appreciate a short e-mail message if you like Clock^3 and have decided to use it for yourself. This at least gives me an idea of how it is being received out there.
I give my permission to include Clock^3 in any freeware or shareware CD. However, please inform me if your intention, so that I can keep track of which CDs contain my software.
Please direct all correspondence concerning Clock^3 to: dondi@cs.ucla.edu. Enjoy!
